Celestin Apprentice 7

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C / Applications / Moscow ML 1.42 / README.Mac < prev next >

Wrap

Text File | 1997-07-29 | 25.8 KB | 638 lines | [TEXT/Moml]

1997Jul25 e Moscow ML for the Apple Macintosh™ mosml is a port of Moscow ML 1.42 to the Apple Macintosh. It was done by e (Doug Currie) in mid-July 1997 based on my previous ports. Read This if Nothing Else ------------------------- Typing an expression followed by the Enter key (or Option-Return), causes the expression to be sent to mosml for evaluation. Try typing: help "lib"; followed by Enter. There are two applications sets, identical in function, but customized for the PPC and m68k SANE. If you are not using Moscow ML on a PowerMac, you should put the PowerMac apps in the trash, and extract (by double clicking the .sea file) the 68k applications for your machine. You must have a PowerMac, or Quadra, or a M68030 or M68020 based Mac. For a PowerMac, use the PPC versions. otherwise use the SANE version. See MacReleaseNotes.txt for improvements since version 1.31. Credits/Support --------------- mosml is freeware. The entire source code for mosml is available. A number of authors have contributed to its development; see the file copyrght/copyrght.cl for restrictions on charging money for distribution of this software. I have tested mosml on a PowerMac (StarMax 4200) and, very briefly, on a Mac IIfx. I have not extensively stress tested memory requirements. I usually run with 8M allocated to mosml, but it will probably run with much less. It will launch and open files in 1M. Running the full library test requires about 9M. Comments/questions about the port should be directed to <e@flavors.com>. Comments/questions about Moscow ML should probably be directed elsewhere, as I am not an expert in ML or its implementation! Please read this file, and any other README or documentation that accompanies this release before sending questions to me or any of the other authors, mailing lists, or newsgroups. See the SML FAQ, and newsgroup comp.lang.ml which I watch via the SML-LIST mailing list. Getting Started --------------- Extract the files onto your hard disk. The self extracting archive should create a mosml folder. Inside this folder are the application archives, the ppc applications and shared libraries, the mosml image, and library files. The PPC version of mosml-mac is now supplied as a pair of files: a shared library containing the bulk of mosml with the user interface, and a small (16k byte) application. The two files must be in the same folder, or else the shared library must in the Extensions folder in your System Folder. There is a second pair of PPC application and shared library for the creation of mosml based CGIs. So in total there are four PPC specific files: mosml142app - the mosml application mosml142app.lib - its shared library mosml142cgi - the cgi application mosml142cgi.lib - its shared library In the application archive mosml142m68.sea there are two 68k applications: mosml142m68 - the mosml application mosml142m68cgi - the cgi application I've distributed the 68k applications as self extracting archives because having more than one set on the machine causes the Finder grief. if you have a 68k based Mac, trash the four PPC files and double click on the application archive mosml142m68.sea and select the mosml (default) folder for the target of the extraction. Each of the above sets, PPC and 68k, provide the same capabilities except that the first PPC set only runs on PowerMacs, and runs faster on PowerMacs than the 68k set. Keep the version for your Mac and trash the other version. From now on I'll call the version you kept "mosml" and "mosml-cgi." The binary image file "mosml.image" is loaded automatically when mosml is launched. mosml then loads some library files. It's important to avoid moving the image or library files; they should be left where installed (relative to mosml and the mosml folder). Now you are running mosml interactively. Typing expressions, followed by the Enter key (or Option-Return), causes the expression to be sent to mosml for evaluation. Try typing: help "lib"; followed by Enter. The Command menu contains mosml specific commands. Use these menu items to use, load, compile, etc. The meaning of these commands is documented in the Moscow ML documentation. The File, Edit, Search, and Windows menus are for using the built in editor. Also in the Edit menu is a Styles item for setting preferences (which are recorded in a "Mosml Preferences" file in your Preferences Folder). Later you can use the link function to build your own images. If you name your image "mosml.image" then it will be loaded automatically at launch instead of the original mosml image. You can also select an image to load at launch time using the command line, via drag and drop, or through naming conventions for applications and images; see below. Also below is a section called eConsole User Notes which describes how to use the console and editor features. Here are some newer features specific to the mosml version of eConsole... A command in the Search menu, Open Selection, can be used to open a file by selecting its name in any window and typing Command-D. This can also be used with mosml's error messages; in this case the file that caused the error will be opened, and the error text scrolled-to and highlighted. For example, selecting the line: File "errortest.sml", line 3-6, characters 4-75: and typing Command-D (or selecting the Open Selection menu item) will open the file errortest.sml in an edit buffer with the four lines highlighted. This only works for files in the current directory, but this is almost always where files will be if the compiler is complaining about them. The Console remembers the end point of the last input (plus Mosml's response, if any) and refuses to allow backspacing past that point. It beeps in response. A common new-user problem occurs when typing an expression without a trailing semicolon -- it results in no response; a natural reaction is to backspace to the previous line, add the semicolon, and type Enter again (rather then simply typing the semicolon and Enter). Unfortunately, this results in the expression being entered twice since the rule is that all text in the "run" near or behind the insert point is sent when Enter is typed. By preventing you from backing up to connect two text "runs" the problem is avoided. You can still use Cut or Clear to remove text from the Console window, if desired. There is a Command menu item called End of Input. It is intended to emulate the Control-D in UNIX. Using the End of Input command, or its command key equivalent <Command-;> (that's the Command key and Semicolon) from toplevel will cause Mosml to quit. Using the End of Input command while awaiting input will cause any typed characters to be Entered, and then whatever characters are available to be returned, even if there are none or fewer than requested. Cow Icons --------- My nine (now almost eleven) year old daughter, Megan, drew the icons. She is better at it than me. I chose a cow for the icon for three reasons: 1) "cow" are the letters missing from mosml 2) Caml Light uses a camel, so I though an animal face would be appropriate 3) I think cows are nice. Cows in New Hampshire look _something_ like the icon. They are white with blotchy black spots. If there are any Moscow ML users out there who are also artists, please feel free to contribute more polished icons! Launching, AppleScript, CGI --------------------------- Mosml-mac has many new features related to AppleScript, AppleEvents, and the creation of CGI applications. CGIs are created by duplicating the mosml-cgi application and giving it and an image file appropriate names. Other tools can be created by duplicating and renaming the mosml application, and optionally using AppleScript to customize startup behavior. (All this application duplicating is why mosml is now implemented as a shared library!) In the interest of saving bits on your disk, I will not duplicate the description of these capabilities here. See the sections - image pathname heuristic - cgi support - new environment variables - AppleScript library module - AppleEvent «event miscdosc» in the file MacReleaseNotes.txt, and examples in the folder e_SML. Command Lines ------------- [Command lines are very non-Mac. You don't need to use them unless you need to use mosmllex, or are bootstrapping a new version.] If mosml cannot find the image file, or if the command key is held down when mosml is launched, then mosml will display a single question mark and await a command line. [The command key is the one with an apple or a "freeway interchange" symbol on it.] The Moscow ML documentation describes command lines. The command line options are specific to the image loaded. The general format is: <image-name> <command-line-options> Examples: :mosml.image -stdlib Bang:mosml:src:mosmllib: :mosml.image -stdlib Bang:mosml:src:mosmllib: -P full :mosmllex.image :src:toolssrc:Deplex.lex Note: when specifying -stdlib, or -I include paths, it is best to provide complete pathnames. A relative name for the image is fine since generally it will go unused after the image is loaded, but paths are recorded verbatim and become useless as soon as chDir() is executed. When launched with the command key down, mosml will type the command line it would have executed had no keys been held down. This can be copied and pasted into the mosml console to customize the startup, e.g., add "-P full" or "-P none" after the typed command line to change the set of library files initially loaded. See the Moscow ML documentation for these sets. WARNING: The command line parser will barf at pathnames with spaces in them. The entire path from the root to the image file, and to stdlib, should only contain volumes and directories without spaces (or returns!) in their names. [Actually, if you surround the pathname with quotes ('name with space' or "name' with space") it should work OK.] Library Status -------------- Although much of it is UNIX derived, a surprising amount of the library now works with the Mac. In particular, walking directory structures, and getting information about files, elapsed/used time, time of day, and dates are all working. In fact, as of this release, the Mac version is ahead of the DOS and UNIX versions in capability. In particular, the Mac version: - has the mosmldep capability built into a new make function - has the linker integrated into the toplevel environment. One compromise was necessary in Path.sml -- it assumes that the pathname string can be used to determine if a path is relative to the current working directory or absolute (relative to "root"). While it is always the case that Mac pathnames starting with ":" are relative, all other pathnames can be relative or absolute. The Mac tries its darndest to find the file somewhere. So, I made the following choice: if the name starts with a ":" then it's relative, else if it contains a ":" it's absolute, else it's relative. This seems to handle common cases (i.e., it's rare to store files at root level). Path.sml also has assumptions built in about how pathname arcs "." and ".." behave. These are just file (or directory) names on the Mac. The Mac approach of "::" meaning up versus ":" meaning down is very dissimilar to the UNIX approach; I tried to make Path.sml work as best I could. It should do the right thing in most cases, certainly all common and canonical cases. There are also some differences in how file system links work. Mac aliases are not 100% like UNIX links. For example, readLink() returns the absolute pathname of the original file on the Mac. The Mac implementation of readDir shares a bug with some other mosml implementations: if you modify the contents of a directory while it is open for reading, the results are unpredictable. Configuration ------------- mosml remembers your Styles preferences in a Preferences Folder file. [You need to understand Mac resources and ResEdit for the rest of the Configuration section to make sense. Don't worry, you don't need to know any of this to use mosml.] The Mac version of mosml simulates UNIX environment variables with resources of type 'ENV '. The resource number doesn't matter, the resources are identified by name. The format of an 'ENV ' resource is simply a C string. mosml only looks for one 'ENV ' variable called CAMLRUNPARAM. It is used to configure the memory manager. I don't know where it's documented (probably the Caml Light distribution). A sensible value for this string is provided as an 'ENV ' resource in the mosml application. If the resource is not found, another sensible value is used. You may add 'ENV ' resources to the mosml application (or to the system, although I wouldn't recommend it) and they can be read using the function Process.getEnv; here's an example... - load "Process.uo"; > val it = () : unit - Process.getEnv "VERSION"; > val it = SOME "mosml 1.42e" : string option - There is also a 'STR#' resource in the mosml application called econfigstrs. The five strings in this string list are used to form the default command line and console window title. They are: - image name :mosml.image [*] - stdlib relative path :lib: [*] - optional -P - optional default - console name Mosml Console When mosml uses the default command line, it converts the stdlib relative path and the image name (marked with [*]) to absolute pathnames before passing them to the image. The image name in econfigstrs is used only if (a) no image was dragged and dropped onto mosml to launch it (in which case the dropped image would be used) (b) the application name does not end in ".app" AND no image was found in the application's directory with the same name as the application, but with ".app" replaced by ".image" (in which case that image is used) Mac toplevel ------------ The mosml toplevel environment on the Macintosh is extended from the UNIX/DOS version. There are four new names: make -- see below link -- see below moolevel -- see below getDir -- same as FileSys.getDir The first three are documented below. The last one, getDir is used by the Command menu. The make and link functions can be used to build complete mosml applications without any other tools, i.e., without a UNIX shell or make program. Together with mosmllex and mosmlyac, make and link can be used to bootstrap mosml. [If you start from the UNIX distribution you will also need perl, e.g., MacPerl, and you may need to preprocess some files with the C preprocessor or by hand -- the Mac source distribution has these files included "pre-processed."] make ---- The make command compiles all files in a directory needing recompilation. It has all the compile capabilities of mosmlc, plus it finds dependencies among the files. It only compiles what needs to be compiled. make : string -> string -> string list -> string -> unit Evaluating: make <oset> <stdlib> [<dir1>..<dirN>] <path> is equivalent to running mosmlc as follows: mosmlc -P <oset> -stdlib <stdlib> -I <dir1> .. -I <dirN> <files...> where <files...> is a subset of the files in directory <path> determined by tracing out the dependencies among the files and their need for compilation. The make command uses the mosmldeps parser to find dependencies for all files in a directory, computes the transitive closure of these dependencies, finds a consistent ordering for the files, tests each file in turn to see if it needs compilation (including tests upon modification times of units outside the target directory as long as they're visible to find_in_path()), and compiles the files if necessary. It takes as arguments -stdlib and -I paths and -P so it can be used to compile the library and compiler directories. A file needs compilation if: 1- there is no corresponding object file, "object" 2- the mtime of the object is older than the epoch 3- the mtime of the source is newer than mtime of the object 4- the mtime of any dependency is newer than the mtime of the object where the epoch is a built in time variable, currently Time.zeroTime. Make keeps a cache of file dependencies; when run a second or subsequent time the cache is consulted and verified based on the mtime of the source file. This can save considerable time. If you ever need to flush this cache (although I can't think of why you would) see moolevel below. Caveats: make doesn't know about cpp, yacc, lex, sed, awk, perl, etc. It does report when it finds ".grm" files without corresponding ".sig" and ".sml" files, for example, (and the same for .mlp & .lex) but these must be made manually. I have created a mosmlyac-mac which I have used to compile the .grm files, and as I said above, mosml can run mosmllex with the command line, and I have used this technique to compile the .lex files. moolevel -------- moolevel : int ref moolevel controls the verbosity of make. 0: no messages 1: error messages 2: compile messages 3: progress messages It defaults to 1, but I personally like level 2. As a special hack, if moolevel is negative, then it is negated, and the cache of file dependencies is cleared. You should never need this. link ---- link : string -> bool * bool -> bool * string -> string \ -> string list -> string list -> unit link is the link portion of mosmlc. Evaluating: link <file> (<g>,<h>) (<a>,<oset>) <stdlib> [<dir1>..<dirN>] [<file1>..<fileN>] is equivalent to running mosmllnk as follows mosmllnk -o <file> {-g} {-noheader} {-noautolink} -P <oset> -stdlib <stdlib> \ -I <dir1> .. -I <dirN> <file1>..<fileN> where -g is included if <g> is true, -noheader is included if <h> is true, and -noautolink is included if <a> is false. If <oset> is "" then it is replaced by "default" If <a> is true then link does the following: 0- <oset> is ignored, use "" or any string 1- trace out all load dependencies of <file1>..<fileN> 2- include in the list of files to be linked all other files depended upon if they can be found in any of the specified paths 3- construct a legal link order for the files 4- then link this list as usual Typically, simply specifying your Main program to be linked will find all the required .uo files and put them in the right order. Examples -------- To create a new mosml project, put all the source files in a new directory, "project." Don't put any incomplete or irrelevant sources in the same directory or they will be compiled, too. Assuming your project only depends on library files, evaluate: let val base = "pathname of the mosml directory:" in make "full" (base ^ "lib") [] (base ^ "project") end; to compile all your files. Evaluate this each time you have made changes in your sources to keep the object files up to date. Here is a sample make and link script to build mosml.image: (* ********************************** *) load "Path"; load "Process"; val home = case Process.getEnv "PATH_TRANSLATED" of SOME n => Path.dir n | NONE => ":" ; moolevel := 2; (* to compile the toplevel mosml image and the lexer *) let val base = home ^ "src:" in valuepoly := false; make "none" (base ^ "mosmllib") [] (base ^ "mosmllib"); valuepoly := true; make "none" (base ^ "mosmllib") [] (base ^ "compiler"); make "none" (base ^ "mosmllib") [(base ^ "compiler")] (base ^ "toolssrc"); make "none" (base ^ "mosmllib") [(base ^ "compiler")] (base ^ "lex") end; (* to build the toplevel mosml image into file "testtop.image" *) let val base = home ^ "src:" in chDir base; chDir "::"; link "testtop.image" (true,true) (* -g -noheader *) (true,"") (* -autolink -P *) (base ^ "mosmllib") [(base ^ "compiler"),(base ^ "toolssrc")] ["Maine.uo"] end; (* ********************************** *) eConsole User Notes ------------------- 1. Interacting with the interpreter Interaction with the interpreter's read-eval-print (REP) loop is done inside the "Mosml Console" window. The contents of the interaction window can be edited by the user. This window also acts as the default standard output port (and input port). Consequently, the interpreter sends its output to the interaction window. User input and system output are displayed with different fonts. By default, user input is in bold face (but this and other attributes of the window can be changed with the "Styles..." item in the Edit menu). Normally, the user types an expression and then "sends" it to the interpreter to be evaluated. The result of the evaluation is then output to the interaction window. The preferred way of evaluating an expression is to place the insertion point (caret) immediately after the expression to evaluate and then typing the <enter> key. An alternative method is to use the <opt-return> (i.e. press the <return> key while pressing the <option> key). When <enter> is pressed, the sequence of "user input" characters immediately preceding the insertion point are sent to the interpreter. Because it doesn't check for a properly formed expression, the <enter> key is useful for programs doing text oriented input. Arbitrary text can also be sent to the interpreter by selecting the text and typing <opt-return> or <enter>. These interaction mechanisms also work from windows associated to files (i.e., in an edit buffer). However, the result of evaluation is always displayed in the interaction window. 2. Basic editing It is assumed that you are familiar with standard Macintosh editing techniques. If not, you should consult your Getting Started disks and Macintosh users' manuals. On all keyboards the following keys are defined: delete - erase character before cursor position tab - indent current line return - insert a new line and move to the left margin (and then do a <tab> if autoindent is selected for the window) opt-return - send the expression preceding the insertion point enter - send the user input preceding the insertion point 3. Special keys On extended keyboards the following special keys are supported: F1 - F4 - equivalent to Undo, Cut, Copy and Paste F5 - F15 - function keys (not used) del> - erase character after the insertion point home - scroll text to the top of the edit buffer end - scroll text to the bottom of the edit buffer page up - scroll text up a page page down - scroll text down a page Note that these last four do not move the insertion point, just scroll. 4. Arrow keys Arrow keys (when available) move the insertion point in the corresponding direction: left - move cursor to the left one character right - move cursor to the right one character up - move cursor up one line down - move cursor down one line Arrow keys can be modified with the <shift>, <option>, and <command> keys. The <shift> key may be used to extend the text selection per Apple standards. Each selection has an anchor end and an active end. Generally, the active end is the last end you moved, the anchor end doesn't move. When the <shift> key is held down, the selection's active end is moved by the arrow keys. The <option> key may be used with the arrow keys to move the insertion point left or right by word, or up or down by page. <Shift> and <option> together may be used to move the active end of the selection left or right by words, or up or down by pages. The <command> key may be used with the arrow keys to move the insertion point left or right to the beginning or end of the line, or up or down to the beginning or end of the text. <Shift> and <command> together may be used to move the active end of the selection to start or end of the line or text. When <shift>, <option>, and <command> are held down together, the up or left arrow will make the beginning of the selection the active end, and the down or right arrow will make the end of the selection the active end. 5. Emacs commands [Sorry, with this version most Emacs commands are absent.] A small subset of Emacs compatible command keys are supported by the editor. Some of these commands make use of the <control> key. The following table lists the Emacs compatible command keys using the following abbreviations: C = <control> key, M = <option> key (Emacs' "meta" key). Commands which move the insertion point: C-f - forward character C-M-f - forward S-expression C-b - backward character C-M-b - backward S-expression C-a - beginning of line C-M-a - beginning of S-expression C-m - select enclosing S-expression C-M-m - select enclosing S-expression C-e - end of line C-M-e - end of S-expression C-p - previous line C-n - next line Commands which modify the buffer: C-d - delete forward (same as del> key) C-del> - delete to end of line C-k - same as C-del> C-o - open line Other commands: M-return - same as <opt-return> 6. Mouse The editing action is specified by the number of mouse button clicks: single - position insertion point double - select word triple - select line Dragging after one of these clicks extends the selection by character, word, or line respectively; the anchor point is the original click position, the active end is the other end of the selection. After a click-drag, the active end can be moved with <shift> clicks or <shift> arrow keys. The anchor and active ends of the selection can be swapped with <option+shift+click>, or <option+shift+command> up/down or left/right arrow keys. 7. Scrolling Holding down <command>, <shift>, <option>, and <control> keys speeds up scrolling when mousing in the arrows of the scroll bar. The more keys you hold down the faster it scrolls (exponentially). Live scrolling is also supported: grab the scrollbar's "thumb" indicator and drag it around; the text will follow. 8. Editor limitations The text size is limited by memory space. There is a limit of 32,000 lines (not characters) per window. The editor has been used with files several hundred kilobytes in size. Credits: Thanks to Marc Feeley for contributing to the eConsole User Notes.